using JetBrains.Annotations;



namespace Fine.Collections.Intf
{

    /// <summary>
    /// Associative array, a map of a <i>key</i> to a <i>value</i>.
    /// </summary>
    /// <typeparam name="K">type of key.</typeparam>
    /// <typeparam name="V">type of value (associated object).</typeparam>
    public interface RMap<K, out V>
    {

        /// <summary>
        /// View of keys.
        /// </summary>
        [NotNull]
        RSet<K> Keys { get; }

        /// <summary>
        /// View of all values.
        /// </summary>
        [NotNull]
        RCollection<V> Values { get; }

        /// <summary>
        /// View of alll entries.
        /// </summary>
        [NotNull]
        RCollection<RMapEntry<K,V>> Entries { get; }


        /// <summary>
        /// Looks for the pair with the specified key.
        /// </summary>
        /// <param name="key">key to look for.</param>
        /// <returns>value of the found pair (if found).</returns>
        [NotNull]
        SearchResult<V> Find(K key);


        /// <summary>
        /// Associative indexator (read only).
        /// Allows to get <c>value</c> by the specified <c>key</c>.
        /// </summary>
        /// <param name="key">key to look for.</param>
        /// <returns>found value, or <i>default(V)</i> if the key is not found.</returns>
        V this[K key] { get; }
        
        
        /// <summary>
        /// Count of pairs in the list.
        /// </summary>
        int Count { get; }


        /// <summary>
        /// Checks whether the collection is empty.
        /// </summary>
        bool IsEmpty { get; }


        /// <summary>
        /// Checks whether the collection has at least one pair.
        /// </summary>
        bool IsNotEmpty { get; }


        /// <summary>
        /// Checks whether this map contains the specified key.
        /// </summary>
        /// <param name="key"></param>
        /// <returns></returns>
        bool ContainsKey(K key);

    }
    
    
}
